@oclif/command

What is @oclif/command?

@oclif/command is a framework for building command-line interface (CLI) applications. It provides a robust set of tools and conventions for creating, organizing, and managing CLI commands, arguments, and options.

What are @oclif/command's main functionalities?

Creating a Basic Command

This feature allows you to create a basic command that prints 'Hello, world!' to the console. The Command class is extended to define the behavior of the command.

const { Command } = require('@oclif/command');

class HelloWorldCommand extends Command {
  async run() {
    this.log('Hello, world!');
  }
}

HelloWorldCommand.run();

Adding Arguments and Flags

This feature allows you to add arguments and flags to your command. In this example, the command takes an optional 'name' argument and a 'greeting' flag to customize the output.

const { Command, flags } = require('@oclif/command');

class GreetCommand extends Command {
  async run() {
    const { args, flags } = this.parse(GreetCommand);
    const name = args.name || 'world';
    const greeting = flags.greeting || 'Hello';
    this.log(`${greeting}, ${name}!`);
  }
}

GreetCommand.args = [
  { name: 'name' }
];

GreetCommand.flags = {
  greeting: flags.string({ char: 'g', description: 'greeting to use' })
};

GreetCommand.run();

Command Aliases

This feature allows you to define aliases for your commands. In this example, the 'HelloWorldCommand' can be invoked using 'hw' or 'hello' as aliases.

const { Command } = require('@oclif/command');

class HelloWorldCommand extends Command {
  async run() {
    this.log('Hello, world!');
  }
}

HelloWorldCommand.aliases = ['hw', 'hello'];

HelloWorldCommand.run();

Other packages similar to @oclif/command

commander

Commander is a popular library for building command-line interfaces. It provides a simple and flexible API for defining commands, arguments, and options. Compared to @oclif/command, Commander is more lightweight and has fewer built-in features, but it is easier to get started with for simple CLI applications.

yargs

Yargs is another library for building command-line interfaces. It focuses on providing a powerful and user-friendly API for parsing arguments and generating help messages. Yargs offers more advanced argument parsing capabilities compared to @oclif/command, but it may require more configuration for complex CLI applications.

caporal

Caporal is a full-featured framework for building command-line applications. It provides a rich set of features for defining commands, arguments, options, and subcommands. Caporal is similar to @oclif/command in terms of functionality, but it has a different API and design philosophy.

README

@oclif/command

This library been replaced by @oclif/core and is now in maintenance mode. We will only consider PRs that address security concerns.

oclif base command

This is about half of the main codebase for oclif. The other half lives in @oclif/config. This can be used directly, but it probably makes more sense to build your CLI with the generator.

Usage

Without the generator, you can create a simple CLI like this:

TypeScript

#!/usr/bin/env ts-node

import * as fs from 'fs'
import {Command, flags} from '@oclif/command'

class LS extends Command {
  static flags = {
    version: flags.version(),
    help: flags.help(),
    // run with --dir= or -d=
    dir: flags.string({
      char: 'd',
      default: process.cwd(),
    }),
  }

  async run() {
    const {flags} = this.parse(LS)
    let files = fs.readdirSync(flags.dir)
    for (let f of files) {
      this.log(f)
    }
  }
}

LS.run()
.catch(require('@oclif/errors/handle'))

JavaScript

#!/usr/bin/env node

const fs = require('fs')
const {Command, flags} = require('@oclif/command')

class LS extends Command {
  async run() {
    const {flags} = this.parse(LS)
    let files = fs.readdirSync(flags.dir)
    for (let f of files) {
      this.log(f)
    }
  }
}

LS.flags = {
  version: flags.version(),
  help: flags.help(),
  // run with --dir= or -d=
  dir: flags.string({
    char: 'd',
    default: process.cwd(),
  }),
}

LS.run()
.catch(require('@oclif/errors/handle'))

Then run either of these with:

$ ./myscript
...files in current dir...
$ ./myscript --dir foobar
...files in ./foobar...
$ ./myscript --version
myscript/0.0.0 darwin-x64 node-v9.5.0
$ ./myscript --help
USAGE
  $ @oclif/command

OPTIONS
  -d, --dir=dir  [default: /Users/jdickey/src/github.com/oclif/command]
  --help         show CLI help
  --version      show CLI version

See the generator for all the options you can pass to the command.